GtkImage
<!-- ##### SECTION Short_Description ##### -->
-A widget displaying a graphical image
+A widget displaying an image
<!-- ##### SECTION Long_Description ##### -->
<para>
-The #GtkImage widget displays a graphical image. The image is typically created
-using gdk_image_new.
-</para>
-<para>
-The pixels in a #GtkImage may be manipulated by the application after creation,
-as #GtkImage store the pixel data on the client side. If you wish to store the
-pixel data on the server side (thus not allowing manipulation of the data after
-creation) you should use #GtkPixmap.
+The #GtkImage widget displays an image. Various kinds of object
+can be displayed as an image; most typically, you would load a
+#GdkPixbuf ("pixel buffer") from a file, and then display that.
+There's a convenience function to do this, gtk_image_new_from_file(),
+used as follows:
+<programlisting>
+ GtkWidget *image;
+ image = gtk_image_new_from_file ("myfile.png");
+</programlisting>
+If the file isn't loaded successfully, the image will contain a
+"broken image" icon similar to that used in many web browsers.
+If you want to handle errors in loading the file yourself,
+for example by displaying an error message, then load the image with
+gdk_pixbuf_new_from_file(), then create the #GtkImage with
+gtk_image_new_from_pixbuf().
+</para>
+<para>
+The image file may contain an animation, if so the #GtkImage will
+display an animation (#GdkPixbufAnimation) instead of a static image.
+</para>
+<para>
+#GtkImage is a subclass of #GtkMisc, which implies that you can
+align it (center, left, right) and add padding to it, using
+#GtkMisc methods.
+</para>
+<para>
+#GtkImage is a "no window" widget (has no #GdkWindow of its own),
+so by default does not receive events. If you want to receive events
+on the image, such as button clicks, place the image inside a
+#GtkEventBox, then connect to the event signals on the event box.
+For example, here is some code that handles button press events
+on a #GtkImage:
+<programlisting>
+ static void
+ button_press_callback (GtkWidget *event_box,
+ GdkEventButton *event,
+ gpointer data)
+ {
+ g_print ("Event box clicked at coordinates %d,%d\n",
+ event->x, event->y);
+
+ /* Returning TRUE means we handled the event, so the signal
+ * emission should be stopped (don't call any further
+ * callbacks that may be connected). Return FALSE
+ * to continue invoking callbacks.
+ */
+ return TRUE;
+ }
+
+ static GtkWidget*
+ create_image (void)
+ {
+ GtkWidget *image;
+ GtkWidget *event_box;
+
+ image = gtk_image_new_from_file ("myfile.png");
+
+ event_box = gtk_event_box_new ();
+
+ gtk_container_add (GTK_CONTAINER (event_box), image);
+
+ g_signal_connect (G_OBJECT (event_box),
+ "button_press_event",
+ G_CALLBACK (button_press_callback),
+ image);
+
+ return image;
+ }
+</programlisting>
+</para>
+<para>
+When handling events on the event box, keep in mind that coordinates
+in the image may be different from event box coordinates due to
+the alignment and padding settings on the image (see #GtkMisc).
+The simplest way to solve this is to set the alignment to 0.0
+(left/top), and set the padding to zero. Then the origin of
+the image will be the same as the origin of the event box.
+</para>
+
+<para>
+Sometimes an application will want to avoid depending on external data
+files, such as image files. GTK+ comes with a program to avoid this,
+called <application>gdk-pixbuf-csource</application>. This program
+allows you to convert an image into a C variable declaration, which
+can then be loaded into a #GdkPixbuf using
+gdk_pixbuf_new_from_inline().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-#GtkPixmap, #GdkRgb
+#GdkPixbuf
</para>
<!-- ##### STRUCT GtkImage ##### -->
<!-- ##### ENUM GtkImageType ##### -->
<para>
-Describes the representation stored by a #GtkImage. If you want to get the image
-from the widget, you can only get the currently-stored representation. e.g. if
-the gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can call
-gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty images, you can
-request any storage type (call any of the "get" functions), but they will all
-return %NULL values.
+Describes the image data representation used by a #GtkImage. If you
+want to get the image from the widget, you can only get the
+currently-stored representation. e.g. if the
+gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can
+call gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty
+images, you can request any storage type (call any of the "get"
+functions), but they will all return %NULL values.
</para>
@GTK_IMAGE_EMPTY: there is no image displayed by the widget
@GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf
@GTK_IMAGE_STOCK: the widget contains a stock icon name
@GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet
-@GTK_IMAGE_ANIMATION:
+@GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation
<!-- ##### FUNCTION gtk_image_get_icon_set ##### -->
<para>
projects / gtk4.git / commitdiff